go-vela/types has been made obsolete. it was responsible for generating the jsonschema that allows for things like IDE validation feedback on Vela YAML pipelines. it was generated via https://github.com/go-vela/types/tree/main/cmd/schema and utilized github.com/alecthomas/jsonschema. schemastore hosts a reference to the published artifact.

github.com/alecthomas/jsonschema has been archived in favor of github.com/invopop/jsonschema, so we're taking the opportunity to upgrade. in the process we're moving from jsonschema draft 4 (2013) to jsonschema 2020-12 (2022) as that is the spec supported by the new library. there are no substantial differences in the generated schema.

the struct tags do most of the heavy lifting for determining the final schema, but there are some necessary customziations due to custom types/unmarshaling we utilize. the library provides some means of doing so by adding certain methods to structs to hook into the generation process. overall, it seems a bit cleaner.

summary of changes

• move schema generation to this repo
• change to use github.com/invopop/jsonschema
• instead of one function handling customization, utilizing provided hooks
• created separate schema package for generating the schema on the fly and to potentially leverage in other places like the CLI for pipeline validation
• added tests and mechanism to validate known good/bad pipelines against schema
• modified CI to utilize the above (see test run)

some notes

jsonschema package

i took the opportunity to look around for alternatives to see what was out there. i think i would have liked to explore using https://github.com/swaggest/jsonschema-go although it doesn't support 2020-12 yet. most notably, it drops the need for separate jsonschema struct tag, instead relying on json and other "direct" tags - the invopop/jsonschema maintainers even reference that as something they wish to move toward.

jsonschema validation

i was thinking about adding in validation. the most notable package for this is https://github.com/santhosh-tekuri/jsonschema (and we're using their provided CLI for the tests that are ran via shell), however it can currently only read in actual files. you provide it with a filename reference which can be a remote URL or local file and tries to resolve it.

i found https://github.com/kaptinlin/jsonschema which seems to address that aspect, but it looks almost too new. however, i did try to use it but ran into some issues where it would claim some valid pipelines were invalid.

i decided to not pursue built-in validation at this time, but it might be worth considering in the future. especially when it comes to validating pipelines using the schema in the Vela CLI. there, we could use the previous library by writing a temp file of the schema (or loading the remote, published schema) and loading the pipeline YAML to validate. generating schema in memory and passing that to the validator seems a bit nicer than utilizing file system or pulling it in remotely 🤷🏼

schemastore

once merged and new schema is published we need to provide a PR to https://github.com/SchemaStore/schemastore to provide the new link. we could fast track a little by generating and uploading schema to the last release manually for now since we just reference the latest release for the schema.json artifact 🤔